=begin pod :kind("Programs") :subkind("programs") :category("programs")

=TITLE Running Raku

=SUBTITLE How to run Rakudo, a Raku implementation, and the command line
options you can use with it.

=head1 NAME

raku - Rakudo Raku Compiler

=head1 SYNOPSIS

=for code :lang<usage>
raku [switches] [--] [programfile] [arguments]

=head1 DESCRIPTION

With no arguments, it enters a REPL. With a C<[programfile]> or the C<-e>
option, compiles the given program and by default also executes the
compiled code.

=begin code :lang<usage>
  -                    read program source from STDIN or start REPL if a TTY
  -c                   check syntax only (runs BEGIN and CHECK blocks)
  --doc                extract documentation and print it as text
  -e program           one line of program, strict is enabled by default
  -h, --help           display this help text
  -n                   run program once for each line of input
  -p                   same as -n, but also print $_ at the end of lines
  -I path              adds the path to the module search path
  -M module            loads the module prior to running the program
  --target=stage       specify compilation stage to emit
  --optimize=level     use the given level of optimization (0..3)
  --rakudo-home=path   Override the path of the Rakudo runtime files
  -o, --output=name    specify name of output file
  -v, --version        display version information
  -V                   print configuration summary
  --stagestats         display time spent in the compilation stages
  --ll-exception       display a low level backtrace on errors
  --doc=module         use Pod::To::[module] to render inline documentation
  --repl-mode=interactive|non-interactive
                       when running without "-e" or filename arguments,
                       a REPL is started. By default, if STDIN is a TTY,
                       "interactive" REPL is started that shows extra messages and
                       prompts, otherwise a "non-interactive" mode is used where
                       STDIN is read entirely and evaluated as if it were a program,
                       without any extra output (in fact, no REPL machinery is even
                       loaded). This option allows to bypass TTY detection and
                       force one of the REPL modes.
  --profile[=name]     write profile information to a file
                       Extension controls format:
                           .json outputs in JSON
                           .sql  outputs in SQL
                           any other extension outputs in HTML
  --profile-compile[=name]
                       write compile-time profile information to a file
                       Extension controls format:
                         .json outputs in JSON
                         .sql  outputs in SQL
                         any other extension outputs in HTML
  --profile-kind[=name]
                       choose the type of profile to generate
                         instrumented - performance measurements (default)
                         heap - record heap snapshots after every garbage
                         collector run
  --profile-filename=name
                       provide a different filename for profile.
                       Extension controls format:
                         .json outputs in JSON
                         .sql  outputs in SQL
                         any other extension outputs in HTML
                       This option will go away in a future Rakudo release
  --profile-stage=stage
                       write profile information for the given compilation
                       stage to a file. Use --profile-compile to set name
                       and format
  --full-cleanup       try to free all memory and exit cleanly
  --debug-port=port    listen for incoming debugger connections
  --debug-suspend      pause execution at the entry point
  --tracing            output a line to stderr on every interpreter instr (only if
                       enabled in MoarVM)
=end code

Note that only Boolean single-letter options may be bundled.

The supported values (stages) for C<--target> are:

=begin code :lang<text>
Target     Backend  Description
======     =======  ===========
parse      all      a representation of the parse tree
ast        all      an abstract syntax tree (before optimizations)
optimize   all      an abstract syntax tree (after optimizations)

mbc        MoarVM   MoarVM byte code
jar        JVM      JVM archive
=end code

For C<--profile-filename>, specifying a name ending in C<.json> will write a raw
JSON profile dump. The default if this is omitted is C<profile-I<[timestamp]>.html>.

Please check out the L<document on environment
variables|programs/03-environment-variables> to check for different ways to change the
behavior of the different layers of Raku.

=head1 AUTHORS

Written by the Rakudo contributors, see the CREDITS file.

This manual page was written by Reini Urban, Moritz Lenz and the Rakudo
contributors.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
